
%\documentstyle[times,titlepage,twoside,verbatimfiles]{article}
%\documentstyle[titlepage,twoside,verbatimfiles]{article}

\documentclass[titlepage,twoside]{article}
\usepackage{verbatimfiles,times}

% margins from ~/tex/opengl/*.tex documents
\topmargin -0.3in
\headheight 10pt
\headsep 15pt
%\oddsidemargin -.20in
%\evensidemargin -.20in
\oddsidemargin 0.2in
\evensidemargin 0.2in
%\textwidth 7.1in
\textwidth 6.1in
\textheight 9in
\makeindex

\pagestyle{headings}

\begin{document}

\sloppy

% index a routine name
\def\rndx#1{{\index{#1}\tt #1}}
% index a word
\def\ndx#1{{\index{#1}#1}}

\newcounter{NoteNum}
\def\resetNote{\setcounter{NoteNum}{0}}
\def\takeNote{\addtocounter{NoteNum}{1}(\theNoteNum)}
\def\sameNote{(\theNoteNum)}

\title{ 
{\huge
The OpenGL Utility Toolkit (GLUT) \\ Programming Interface} \\
\vspace{.4in}
API Version 3}
\author{Mark J. Kilgard \\
{\em Silicon Graphics, Inc.}}

\maketitle

\setcounter{page}{0}

\renewcommand{\thepage}{\roman{page}}

OpenGL is a trademark of Silicon Graphics, Inc.  X Window System is
a trademark of X Consortium, Inc.  Spaceball is a registered trademark
of Spatial Systems Inc.

The author has taken care in preparation of this documentation but makes no
expressed or implied warranty of any kind and assumes no 
responsibility for errors or omissions.  No liability is assumed
for incidental or consequential damages in connection with or arising
from the use of information or programs contained herein.

\vspace{.5in}

\begin{center}
Copyright \copyright 1994, 1995, 1996. Mark J. Kilgard.  All rights reserved.
\end{center}

\vspace{.5in}

All rights reserved.  No part of this documentation may be reproduced,
in any form or by any means, without permission in writing from the author.

\newpage

\tableofcontents

\cleardoublepage

\setcounter{page}{1}

\renewcommand{\thepage}{\arabic{page}}

\section{Introduction}

\def\Fortran{{\sc Fortran}}

The OpenGL Utility Toolkit (GLUT) is a programming interface with ANSI C and
\Fortran\ bindings for writing window system
independent OpenGL programs.  The toolkit supports the following functionality:
\begin{itemize}
\item Multiple windows for OpenGL rendering.
\item Callback driven event processing.
\item Sophisticated input devices.
\item An ``idle'' routine and timers.
\item A simple, cascading pop-up menu facility.
\item Utility routines to generate various solid and wire frame objects.
\item Support for bitmap and stroke fonts.
\item Miscellaneous window management functions, including managing overlays.
\end{itemize}
An ANSI C implementation of GLUT for the X Window System \cite{x92} has
been implemented by the author.  Windows NT and OS/2 versions of GLUT
are also available.

This documentation serves as both a specification and a programming guide.
If you are interested in a brief introduction to programming with GLUT,
look for the introductory OpenGL column \cite{kilgard94c}
published in \index{The X Journal}{\em The X Journal}.  For a complete
introduction to using GLUT, obtain the book {\em Programming OpenGL
for the X Window System} \cite{kilgard96}.  GLUT is also used by the
2nd edition of the {\em OpenGL Programming Guide}.
Teachers and students
interested in using GLUT in conjunction with a college-level computer
graphics class should investigate Angel's textbook
{\em Interactive Computer Graphics:
A top-down approach with OpenGL} \cite{angel96} that uses GLUT
for its OpenGL-based examples programs.

The remainder of this section describes GLUT's design philosophy and
usage model.  The following sections specify the GLUT routines, grouped
by functionality.  The final sections discuss usage advice, the
\Fortran\ binding, and implementation issues.  Appendix A enumerates
and annotates the logical programmer visible state maintained by GLUT.
Appendix B presents the ANSI C GLUT API via its header file.  Appendix
C presents the \Fortran\ GLUT API via its header file.

\subsection{Background}

One of the major accomplishments in the specification of OpenGL
\cite{segal92,arb92} was the isolation of window system dependencies
from OpenGL's rendering model.  The result is that OpenGL is window
system independent.

Window system operations such as the creation of a rendering window and
the handling of window system events are left to the native window
system to define.  Necessary interactions between OpenGL and the window
system such as creating and binding an OpenGL context to a window are
described separately from the OpenGL specification in a window system
dependent specification.  For example, the GLX specification
\cite{karlton93} describes the standard by which OpenGL interacts with
the X Window System.

The predecessor to OpenGL is IRIS GL \cite{sgi91a,sgi91b}.  Unlike
OpenGL, IRIS GL {\em does} specify how rendering windows are created
and manipulated.  IRIS GL's windowing interface is reasonably popular
largely because it is simple to use.  IRIS GL programmers can worry
about graphics programming without needing to be an expert in
programming the native window system.  Experience also demonstrated that
IRIS GL's windowing interface was high-level enough that it could be
retargeted to different window systems.  Silicon Graphics migrated from
NeWS to the X Window System without any major changes to IRIS GL's
basic windowing interface.

Removing window system operations from OpenGL is a sound decision
because it allows the OpenGL graphics system to be retargeted to
various systems including powerful but expensive graphics workstations
as well as mass-production graphics systems like video games, set-top
boxes for interactive television, and PCs.

Unfortunately, the lack of a window system interface for OpenGL is a
gap in OpenGL's utility.  Learning native window system APIs such as
the X Window System's Xlib \cite{kilgard94a} or Motif \cite{kilgard94b}
can be daunting.  Even those familiar with native window system APIs
need to understand the interface that binds OpenGL to the native window
system.  And when an OpenGL program is written using the native window
system interface, despite the portability of the program's OpenGL
rendering code, the program itself will be window system dependent.

Testing and documenting OpenGL's functionality lead to the development
of the {\tt tk} and {\tt aux} toolkits.  The {\tt aux} toolkit is used
in the examples found in the {\em OpenGL Programming Guide}
\cite{neider93}.  Unfortunately, {\tt aux} has numerous limitations and
its utility is largely limited to toy programs.  The {\tt tk} library
has more functionality than {\tt aux} but was developed in an {\em ad
hoc} fashion and still lacks much important functionality that IRIS GL
programmers expect, like pop-up menus and overlays.

GLUT is designed to fill the need for a window system independent
programming interface for OpenGL programs.  The interface is designed
to be simple yet still meet the needs of useful OpenGL programs.
Features from the IRIS GL, {\tt aux}, and {\tt tk} interfaces are
included to make it easy for programmers used to these interfaces
to develop programs for GLUT.

\subsection{Design Philosophy}

GLUT simplifies the implementation of programs using OpenGL rendering.
The GLUT application programming interface (API) requires very few
routines to display a graphics scene rendered using OpenGL.  The GLUT
API (like the OpenGL API) is stateful.  Most initial GLUT state is
defined and the initial state is reasonable for simple programs.

The GLUT routines also take relatively few parameters.  No pointers are
returned.  The only pointers passed into GLUT are pointers to character
strings (all strings passed to GLUT are copied, not referenced) and
opaque font handles.

The GLUT API is (as much as reasonable) window system independent.  For
this reason, GLUT does not return {\em any} native window system
handles, pointers, or other data structures.  More subtle window system
dependencies such as reliance on window system dependent fonts are
avoided by GLUT; instead, GLUT supplies its own (limited) set of
fonts.

For programming ease, GLUT provides a simple menu sub-API.  While the
menuing support is designed to be implemented as pop-up menus, GLUT
gives window system leeway to support the menu functionality in
another manner (pull-down menus for example).

Two of the most important pieces of GLUT state are the {\em current
window} and {\em current menu}.  Most window and menu routines affect
the {\em current window} or {\em menu} respectively.  Most callbacks
implicitly set the {\em current window} and {\em menu} to the
appropriate window or menu responsible for the callback.  GLUT is
designed so that a program with only a single window and/or menu will
not need to keep track of any window or menu identifiers.  This greatly
simplifies very simple GLUT programs.

GLUT is designed for simple to moderately complex programs focused on
OpenGL rendering.  GLUT implements its own event loop.  For this
reason, mixing GLUT with other APIs that demand their own event
handling structure may be difficult.  The advantage of a builtin event
dispatch loop is simplicity.

GLUT contains routines for rendering fonts and geometric objects,
however GLUT makes no claims on the OpenGL display list name space.
For this reason, none of the GLUT rendering routines use OpenGL display
lists.  It is up to the GLUT programmer to compile the output from GLUT
rendering routines into display lists if this is desired.

GLUT routines are logically organized into several sub-APIs according
to their functionality.  The sub-APIs are:
\begin{description}
\item[{\em Initialization.}]
Command line processing,
window system initialization, and initial window creation state are controlled
by these routines.
\item[{\em Beginning Event Processing.}]
This routine enters GLUT's event processing loop.  This routine never returns,
and it continuously calls GLUT callbacks as necessary.
\item[{\em Window Management.}]
These routines create and control windows.
\item[{\em Overlay Management.}]
These routines establish and manage overlays for windows.
\item[{\em Menu Management.}]
These routines create and control pop-up menus.
\item[{\em Callback Registration.}]
These routines register callbacks to be called by the GLUT event processing loop.
\item[{\em Color Index Colormap Management.}]
These routines allow the manipulation of color index colormaps for windows.
\item[{\em State Retrieval.}]
These routines allows programs to retrieve state from GLUT.
\item[{\em Font Rendering.}]
These routines allow rendering of stroke and bitmap fonts.
\item[{\em Geometric Shape Rendering.}]
These routines allow the rendering of 3D geometric objects including spheres,
cones, icosahedrons, and teapots.
\end{description}

\subsection{API Version 2}

In response to feedback from the original version of GLUT, GLUT API version
2 was developed.  Additions to the original GLUT API version 1 are:
\begin{itemize}
\item Support for requesting stereo and multisample windows.
\item New routines to query support for and provide callbacks for sophisticated
      input devices: the Spaceball, tablet, and dial \& button box.
\item New routine to register a callback for keyboard function and directional
      keys.  In version 1, only ASCII characters could be generated.
\item New queries for stereo, multisampling, and elapsed time.
\item New routine to ease querying for OpenGL extension support.
\end{itemize}
GLUT API version 2 is completely compatible with version 1 of the API.

\subsection{API Version 3}

Further feedback lead to the development of GLUT API version 3.
Additions to the GLUT API version 2 are:
\begin{itemize}
\item The \rndx{glutMenuStateFunc} has been deprecated in favor of the
      \rndx{glutMenuStatusFunc}.
\item {\tt glutFullScreen} requests full screen top-level windows.
\item Three additional Helvetica bitmap fonts.
\item Implementations should enforce not allowing any modifications
      to menus while menus are in use.
\item \rndx{glutBitmapWidth} and \rndx{glutStrokeBitmap} return the
      widths of individual characters.
\item \rndx{glutGetModifiers} called during a keyboard, mouse, or special
      callback returns the modifiers (Shift, Ctrl, Alt)
      held down when the mouse or keyboard event was generated.
\item Access to per-window transparent overlays when overlay hardware
      is supported.  The routines added are \rndx{glutEstablishOverlay},
      \rndx{glutRemoveOverlay}, \rndx{glutShowOverlay},
      \rndx{glutHideOverlay}, \rndx{glutUseOverlay}, \rndx{glutLayerGet},
      and \rndx{glutPostOverlayRedisplay}.
\item A new display mode called \rndx{GLUT\_LUMINANCE} using OpenGL's
      RGBA color model, but that has no green or blue components.  The red
      component is converted to an index and looked up in a writable
      colormap to determine displayed colors.  See \rndx{glutInitDisplayMode}.

\end{itemize}
GLUT API version 3 should be largely compatible with version 2.  Be
aware that programs that used to (through some degree of fortuitous
timing) modify menus while menus are in use will encounter fatal errors
when doing so in version 3.

Another change in GLUT 3.0 that may require source code
modification to pre-3.0 GLUT programs.  GLUT 3.0 no longer lets a
window be shown without a display callback registered.  This change
makes sure windows are not displayed on the screen without the GLUT
application providing a way for them to be rendered.  In conjunction
with this change, \rndx{glutDisplayFunc} no longer allows {\tt NULL}
to deregister a display callback.  While there is no longer a way to deregister
a display callback, you can still change the change the display
callback routine with subsequent calls to {\tt glutDisplayFunc}.

The display mode mask parameter for {\tt glutInitDisplayMode} and the
milliseconds parameter for {\tt glutTimerFunc} are now
of type {\tt unsigned int} (previously {\tt unsigned long}).

\subsection{Conventions}

GLUT window and screen coordinates are expressed in pixels.  The upper left hand
corner of the screen or a window is (0,0).  X coordinates increase in a
rightward direction; Y coordinates increase in a downward direction.
Note:  This is inconsistent with OpenGL's coordinate scheme that generally
considers the lower left hand coordinate of a window to be at (0,0) but is
consistent with most popular window systems.

Integer identifiers in GLUT begin with one, not zero.  So window identifiers,
menu identifiers, and menu item indices are based from one, not zero.

In GLUT's ANSI C binding, for most routines, basic types ({\tt int},
{\tt char*}) are used as parameters.  In routines where the parameters
are directly passed to OpenGL routines, OpenGL types ({\tt GLfloat})
are used.

The header files for GLUT should be included in GLUT programs
with the following include directive:
\begin{verbatim}
  #include <GL/glut.h>
\end{verbatim}
Because a very large window system software vendor (who will remain
nameless) has an apparent inability to appreciate that OpenGL's API is
independent of their window system API, portable ANSI C GLUT programs should
not directly include {\tt <GL/gl.h>} or {\tt <GL/glu.h>}.  Instead,
ANSI C GLUT programs should rely on {\tt <GL/glut.h>} to include the necessary
OpenGL and GLU related header files.

The ANSI C GLUT library archive is typically named {\tt libglut.a} on Unix
systems.  GLUT programs need to link with the system's OpenGL and GLUT libraries
(and any libraries these libraries potentially depend on).
A set of window system dependent libraries may also be necessary
for linking GLUT programs.  For example, programs using the X11 GLUT
implementation typically need to link with Xlib, the X extension
library, possibly the X Input extension library,  the X miscellaneous
utilities library, and the math library.  An example X11/Unix
compile line would look like:
\begin{verbatim}
  cc -o foo foo.c -lglut -lGLU -lGL -lXmu -lXi -lXext -lX11 -lm
\end{verbatim}

\subsection{Terminology}

A number of terms are used in a GLUT-specific manner throughout this
document.  The GLUT meaning of these terms is independent of the
window system GLUT is used with.  Here are GLUT-specific
meanings for the following GLUT-specific terms:
\begin{description}
\item[{\em \ndx{Callback}}]  A programmer specified routine that can be
registered with GLUT to be called in response to a specific type
of event.  Also used to refer to a specific callback routine
being called.
\item[{\em \ndx{Colormap}}]  A mapping of pixel values to RGB color values.
  Use by color index windows.
\item[{\em \ndx{Dials and button box}}]  A sophisticated input device
consisting of a pad of buttons and an array of rotating dials, often
used by computer-aided design programs.
\item[{\em \ndx{Display mode}}]  A set of OpenGL frame buffer capabilities
that can be attributed to a window.
\item[{\em \ndx{Idle}}]  A state when no window system events are received
for processing as callbacks and the idle callback, if one is registered,
is called.
\item[{\em \ndx{Layer in use}}]  Either the normal plane or overlay.  This
per-window state determines what frame buffer layer OpenGL commands affect.
\item[{\em \ndx{Menu entry}}]  A menu item that the user can select to
trigger the menu callback for the menu entry's value.
\item[{\em \ndx{Menu item}}]  Either a menu entry or a sub-menu trigger.
\item[{\em \ndx{Modifiers}}]  The Shift, Ctrl, and Alt keys that can be held down
simultaneously with a key or mouse button being pressed or released.
\item[{\em \ndx{Multisampling}}]  A technique for hardware antialiasing
generally available only on expensive 3D graphics hardware \cite{akeley93}.  Each
pixel is composed of a number of samples (each containing color and
depth information).  The samples are averaged to determine the
displayed pixel color value.  Multisampling is supported as an
extension to OpenGL.
\item[{\em \ndx{Normal plane}}]  The default frame buffer layer where GLUT window
state resides; as opposed to the {\em overlay}.
\item[{\em \ndx{Overlay}}]  A frame buffer layer that can be displayed preferentially
to the {\em normal plane} and supports transparency to display through to the
{\em normal plane}.  Overlays are useful for rubber-banding effects, text
annotation, and other operations, to avoid damaging the normal plane frame
buffer state.  Overlays require hardware support not present on all systems.
\item[{\em \ndx{Pop}}]  The act of forcing a window to the top of the
stacking order for sibling windows.
\item[{\em \ndx{Pop-up menu}}]  A menu that can be set to appear when a specified
mouse button is pressed in a window.  A pop-menu consists of multiple
menu items.
\item[{\em \ndx{Push}}]  The act of forcing a window to the bottom of the
stacking order for sibling windows.
\item[{\em \ndx{Reshape}}]  The act of changing the size or shape of the window.
\item[{\em \ndx{Spaceball}}]  A sophisticated 3D input device that provides 
six degrees of freedom, three axes of rotation and three axes of
translation.  It also supports a number
of buttons.  The device is a hand-sized ball attached to a base.  By
cupping the ball with one's hand and applying torsional or directional force
on the ball, rotations and translationsare generated.
\item[{\em \ndx{Stereo}}]  A frame buffer capability providing left
  and right color buffers for creating stereoscopic renderings.  Typically,
  the user wears LCD shuttered goggles synchronized with the alternating
  display on the screen of the left and right color buffers.
\item[{\em \ndx{Sub-menu}}]  A menu cascaded from some sub-menu trigger.
\item[{\em \ndx{Sub-menu trigger}}]  A menu item that the user can enter to
cascade another pop-up menu.
\item[{\em \ndx{Subwindow}}]  A type of window that is the child window of
a top-level window or other subwindow.  The drawing and visible region
of a subwindow is limited by its parent window.
\item[{\em \ndx{Tablet}}]  A precise 2D input device.  Like
a mouse, 2D coordinates are returned.  The absolute position of the
tablet ``puck'' on the tablet is returned.  Tablets also support
a number of buttons.
\item[{\em \ndx{Timer}}]  A callback that can be scheduled to be called in
a specified interval of time.
\item[{\em \ndx{Top-level window}}]  A window that can be placed, moved, resized,
etc. independently from other top-level windows by the user.
Subwindows may reside within a top-level window.
\item[{\em \ndx{Window}}]  A rectangular area for OpenGL rendering.
\item[{\em \ndx{Window display state}}]  One of shown, hidden, or iconified.
A shown window is potentially visible on the screen (it may be obscured
by other windows and not actually visible).  A hidden window will
never be visible.  An iconified window is not visible but could
be made visible in response to some user action like clicking on the
window's corresponding icon.
\item[{\em \ndx{Window system}}]  A broad notion 
that refers to both the mechanism and policy of the window system.
For example, in the X Window System both the window manager and the
X server are integral to what GLUT considers the window system.
\end{description}

\input glutapi3.tex

\section{Usage Advice}

There are a number of points to keep in mind when writing GLUT
programs.  Some of these are strong recommendations, others simply
hints and tips.

\begin{itemize}

\item
Do not change state that will affect the way a window
will be drawn in a window's display callback.
Your display callbacks should be idempotent.

\item
If you need to redisplay a window, instead of rendering in
whatever callback you happen to be in, call \rndx{glutPostRedisplay}
(or \rndx{glutPostRedisplay} for overlays).
As a general rule, the only code that renders directly to the screen
should be in called from display callbacks; other types of callbacks
should not be rendering to the screen.

\item
If you use an idle callback to control your animation, use the
visibility callbacks to determine when the window is fully obscured
or iconified to determine when not to waste processor time rendering.

\item
Do not call any GLUT routines between a {\tt glBegin} and {\tt glEnd}.

\item
Do not call any GLUT routines between a {\tt glNewList} and {\tt glEndList}.

\item
Neither GLUT nor the window system automatically reshape sub-windows.
If subwindows should be reshaped to reflect a reshaping of the
top-level window, the GLUT program is responsible for doing this.

\item
Avoid using color index mode if possible.  The RGBA
color model is more functional, and it is less likely to cause colormap
swapping effects.

\item
Do not call any GLUT routine that affects the {\em current window} or
{\em current menu} if there is no {\em current window} or {\em current
menu} defined.  This can be the case at initialization time (before any
windows or menus have been created) or if your destroy the {\em
current window} or {\em current menu}.  GLUT implementations are not
obliged to generate a warning because doing so would slow down the
operation of every such routine to first make sure there was a {\em
current window} or {\em current menu}.

\item
For most callbacks, the {\em current window} and/or {\em current menu} is
set appropriately at the time of the callback.  Timer and idle callbacks
are exceptions.  If your application uses multiple windows or menus,
make sure you explicitly you set the {\em current
window} or {\em menu} appropriately using \rndx{glutSetWindow} or
\rndx{glutSetMenu} in the idle and timer callbacks.

\item
If you register a single function as a callback routine for multiple
windows, you can call \rndx{glutGetWindow} within the callback to
determine what window generated the callback.  Likewise, \rndx{glutGetMenu} can be called to determine what menu.

\item
By default, timer and idle callbacks may be called while a
pop-up menu is active.  On slow machines, slow rendering in an idle
callback may compromise menu performance.  Also, it may be desirable
for motion to stop immediately when a menu is triggered.  In this
case, use the menu entry/exit callback set with \rndx{glutMenuStateFunc}
to track the usage of pop-up menus.

\item
Do not select for more input callbacks than you actually
need.  For example, if you do not need motion or passive motion
callbacks, disable them by passing {\tt NULL} to their callback
register functions.  Disabling input callbacks allows the GLUT
implementation to limit the window system input events that must
be processed.

\item
Not every OpenGL implementation supports the same range of
frame buffer capabilities, though minimum requirements for
frame buffer capabilities do exist.  If \rndx{glutCreateWindow}
or \rndx{glutCreateSubWindow} are called with an {\em initial
display mode} not supported by the OpenGL implementation,
a fatal error will be generated with an explanatory message.
To avoid this, {\tt \index{glutGet} glutGet(GLUT\_DISPLAY\_MODE\_POSSIBLE)}
should be called to determine if the {\em initial
display mode} is supported by the OpenGL implementation.

\item
The Backspace, Delete, and Escape keys generate ASCII characters, so detect
these key presses with the \rndx{glutKeyboardFunc} callback, not
with the \rndx{glutSpecialFunc} callback.

\item
Keep in mind that when a window is damaged, you should assume {\em all}
of the ancillary buffers are damaged and redraw them all.

\item
Keep in mind that after a \rndx{glutSwapBuffers}, you should assume
the state of the back buffer becomes undefined.

\item
If not using {\tt glutSwapBuffers} for double buffered animation,
remember to use \rndx{glFlush} to make sure rendering requests
are dispatched to the frame buffer.  While many OpenGL implementations
will automatically flush pending commands, this is specifically not
mandated.

\item
Remember that it is illegal to create or destroy menus or change, add, or
remove menu items while a menu (and any cascaded sub-menus) are in use
(that is, ``popped up'').  Use the menu status callback to know when to
avoid menu manipulation.

\item
It is more efficient to use {\tt glutHideOverlay} and {\tt glutShowOverlay}
to control the display state of a window's overlay instead of removing
and re-establishing an overlay every time an overlay is needed.

\item
Few workstations have support for multiple simultaneously installed
overlay colormaps.  For this reason, if an overlay is cleared or
otherwise not be used, it is best to hide it using {\tt
glutHideOverlay} to avoid other windows with active overlays from being
displayed with the wrong colormap.  If your application uses multiple
overlays, use {\tt glutCopyColormap} to promote colormap sharing.

\item
If you are encountering GLUT warnings or fatal errors in your programs,
try setting a debugger break-point in \rndx{\_\_glutWarning} or
\rndx{\_\_glutFatalError} (though these names are potentially
implementation dependent) to determine where within your program the
error occurred.

\item
GLUT has no special routine for exiting the program.  GLUT programs
should use ANSI C's {\tt exit} routine.  If a program needs
to perform special operations before quitting the program, use
the ANSI C \rndx{onexit} routine to register exit callbacks.  GLUT
will exit the program unilaterally when fatal errors occur or
when the window system requests the program to terminate.  For
this reason, avoid calling any GLUT routines within an exit
callback.

\item
Definitely, definitely, use the {\tt -gldebug} option to look
for OpenGL errors when OpenGL rendering does not appear to
be operating properly.  OpenGL errors are only reported if
you explicitly look for them!

\end{itemize}

\section{FORTRAN Binding}

All GLUT functionality is available through the GLUT \Fortran\ API.
The GLUT \Fortran\ binding is intended to be used in conjunction with the OpenGL and GLU
\Fortran\ APIs.

A \Fortran\ routine using GLUT routines should include the GLUT \Fortran\
header file.  While this is potentially system dependent, on Unix
systems this is normally done by including after the {\tt SUBROUTINE},
{\tt FUNCTION}, or {\tt PROGRAM} line:
\begin{verbatim}
#include "GL/fglut.h"
\end{verbatim}

Though the \Fortran\ 77 specification differentiates identifiers by
their first six characters only, the GLUT \Fortran\ binding (and the OpenGL
and GLU \Fortran\ bindings) assume identifiers are not limited to 6
characters.

The \Fortran\ GLUT binding library archive is typically named {\tt libfglut.a} on Unix
systems.  \Fortran\ GLUT programs need to link with the system's OpenGL and GLUT libraries
and the respective Fortran binding libraries
(and any libraries these libraries potentially depend on).
A set of window system dependent libraries may also be necessary
for linking GLUT programs.  For example, programs using the X11 GLUT
implementation typically need to link with Xlib, the X extension
library, possibly the X Input extension library,  the X miscellaneous
utilities library, and the math library.  An example X11/Unix
compile line for a GLUT \Fortran\ program would look like:
\begin{verbatim}
  f77 -o foo foo.f -lfglut -lglut -lfGLU -lGLU -lfGL -lGL \
    -lXmu -lXi -lXext -lX11 -lm
\end{verbatim}

\subsection{Names for the FORTRAN GLUT Binding}

Allowing for {\sc Fortran}'s case-insensitivity, the GLUT \Fortran\ binding
constant and routine names are the same as the C binding's names.

The OpenGL \ndx{Architectural Review Board} (ARB) official OpenGL \Fortran\ API prefixes every routine and
constant with the letter F.  The justification was to avoid name
space collisions with the C names in anachronistic compilers.  Nearly
all modern \Fortran\ compilers avoid these name space clashes via other
means (underbar suffixing of \Fortran\ routines is used by most Unix \Fortran\
compilers).

The GLUT \Fortran\ API does {\em not} use such prefixing conventions
because of the documentation and coding confusion introduced by
such prefixes.  The confusion is heightened by
{\sc Fortran}'s default implicit variable initialization so programmers
may realize the lack of a constant prefix as a result of a run-time error.
The confusion introduced to support the prefixes
was not deemed worthwhile simply to support anachronistic
compliers.

\subsection{Font Naming Caveat}

Because GLUT fonts are compiled directly into GLUT programs as data,
and programs should only have the fonts compiled into them that they use,
GLUT font names like {\tt GLUT\_BITMAP\_TIMES\_ROMAN\_24} are really
symbols so the linker should only pull in used fonts.

Unfortunately, because some supposedly modern \Fortran\ compilers
link declared but unused data {\tt EXTERNAL}s, ``GL/fglut.h'' does not
explicitly declare {\tt EXTERNAL} the GLUT font symbols.  Declaring the
GLUT font symbols as 
{\tt EXTERNAL} risks forcing every GLUT \Fortran\
program to contain the data for every GLUT font.  GLUT
Fortran programmers should explicitly declare {\tt EXTERNAL}
the GLUT fonts they use.  Example:
\begin{verbatim}
        SUBROUTINE PRINTA
#include "GL/fglut.h"
        EXTERNAL GLUT_BITMAP_TIMES_ROMAN_24
        CALL glutBitmapCharacter(GLUT_BITMAP_TIMES_ROMAN_24, 65)
        END
\end{verbatim}

\subsection{NULL Callback}

\Fortran\ does not support passing {\tt NULL} as a callback
parameter the way ANSI C does.  For this reason, \rndx{GLUTNULL}
is used in place of {\tt NULL} in GLUT \Fortran\ programs to
indicate a {\tt NULL} callback.

\section{Implementation Issues}

While this specification is primarily intended to describe the GLUT API
and not its implementation, the section describes implementation
issues that are likely to help both GLUT implementors properly
implement GLUT and provide GLUT programmers with information to better
utilize GLUT.

\subsection{Name Space Conventions}

The GLUT implementation should have a well-defined name space for both
exported symbols and visible, but not purposefully exported symbols.
All exported functions are prefixed by {\tt glut}.  All exported macro
definitions are prefixed by {\tt GLUT\_}.  No data symbols are
exported.  All internal symbols that might be user-visible but not
intended to be exported should be prefixed by {\tt \_\_glut}.  Users of
the GLUT API should {\em not} use any {\tt \_\_glut} prefixed symbols.

\subsection{Modular Implementation}

It is often the case that windowing libraries tend to result in large,
bulky programs because a large measure of ``dynamically dead'' code is
linked into the programs because it can not be determined at link time
that the program will never require (that is, execute) the code.  A
consideration (not a primary one though) in GLUT's API design is make
the API modular enough that programs using a limited subset of GLUT's
API can minimize the portion of the GLUT library implementation
required.  This does assume the implementation of GLUT is structured to
take advantage of the API's modularity.

A good implementation can be structured so significant chunks of code
for color index colormap management, non-standard device support (Spaceball,
dial \& button box, and tablet), overlay management, pop-up
menus, miscellaneous window management routines (pop, push, show, hide,
full screen, iconify), geometric shape rendering, and font rendering
only need to be pulled into GLUT programs when the interface to this
functionality is explicitly used by the GLUT program.

\subsection{Error Checking and Reporting}

How errors and warnings about improper GLUT usage are reported to GLUT
programs is implementation dependent.  The recommended behavior in the
case of an error is to output a message and exit.  In the case of a
warning, the recommended behavior is to output a message and continue.
All improper uses of the GLUT interface do not need to be caught or
reported.  What conditions are caught or reported should be based on
how expensive the condition is to check for.  For example, an
implementation may not check every {\tt glutSetWindow} call to determine
if the window identifier is valid.

The run-time overhead of error checking for a very common operation may
outweight the benefit of clean error reporting.  This trade-off is
left for the implementor to make.  The implementor should also
consider the difficulty of diagnosing the improper usage without
a message being output.  For example, if a GLUT program attempts
to create a menu while a menu is in use (improper usage!), this
warrants a message because this improper usage may often be benign,
allowing the bug to easily go unnoticed.

\subsection{Avoid Unspecified GLUT Usage Restrictions}

GLUT implementations should be careful to not limit the conditions
under which GLUT routines may be called.  GLUT implementations are
expected to be resilient when GLUT programs call GLUT routines with
defined behavior at ``unexpected'' times.  For example, a program
should be permitted to destroy the {\em current window} from within a
display callback (assuming the user does not then call GLUT routines
requiring a {\em current window}).  This means after dispatching
callbacks, a GLUT implementation should be ``defensive'' about how the
program might have used manipulated GLUT state during the callback.

\newpage

\appendix

{\raggedbottom
\section{GLUT State}

\input glut_state3.tex

\newpage
}%raggedbottom

\section{glut.h ANSI C Header File}

{\footnotesize
\verbatimlisting{glut.h.notab}
}

\pagebreak

\section{fglut.h FORTRAN Header File}

{\footnotesize
\verbatimlisting{fglut.h.notab}
}

\pagebreak

\addcontentsline{toc}{section}{References}

\begin{thebibliography}{99}

\bibitem{akeley93}
Kurt Akeley, ``RealityEngine Graphics,'' {\em Proceedings of
SIGGRAPH '93}, July 1993.

\bibitem{angel96}
Edward Angel, {\em Interactive Computer Graphics: A top-down approach
with OpenGL}, Addison-Wesley, ISBN 0-201-85571-2, 1996.

\bibitem{crow87}
F.C. Crow, ``The Origins of the Teapot,'' {\em IEEE Computer Graphics
and Applications}, January 1987.

\bibitem{karlton93} Phil Karlton, {\em OpenGL Graphics with the X
Window System}, Ver. 1.0, Silicon Graphics, April 30, 1993.

\bibitem{kilgard93-xsgi} Mark J. Kilgard, ``Going Beyond the MIT Sample
Server:  The Silicon Graphics X11 Server,'' {\em The X Journal}, SIGS
Publications, January 1993.

\bibitem{kilgard93-layers}
Mark Kilgard, ``Programming X Overlay Windows,'' {\em The X Journal},
SIGS Publications, July 1993.

\bibitem{kilgard94a}
Mark Kilgard, ``OpenGL and X, Part 2: Using OpenGL with Xlib,''
{\em The X Journal}, SIGS Publications, Jan/Feb 1994.

\bibitem{kilgard94b}
Mark Kilgard, ``OpenGL and X, Part 3: Integrating OpenGL with Motif,''
{\em The X Journal}, SIGS Publications, Jul/Aug 1994.

\bibitem{kilgard94c}
Mark Kilgard, ``An OpenGL Toolkit,''
{\em The X Journal}, SIGS Publications, Nov/Dec 1994.

\bibitem{kilgard96}
Mark Kilgard, {\em Programming OpenGL for the X Window System},
Addison-Wesley, ISBN 0-201-48359-9, 1996.

\bibitem{neider93}
Jackie Neider, Tom Davis, Mason Woo, {\em OpenGL Programming Guide:
The official guide to learning OpenGL, Release 1}, Addison Wesley, 1993.

\bibitem{arb92}
OpenGL Architecture Review Board, {\em OpenGL Reference Manual:  The
official reference document for OpenGL, Release 1}, Addison Wesley, 1992.

\bibitem{xinput-lib}
Mark Patrick, George Sachs, {\em X11 Input Extension Library Specification}, 
X Consortium Standard, X11R6, April 18, 1994.

\bibitem{xinput-protocol}
Mark Patrick, George Sachs, {\em X11 Input Extension Protocol Specification}, 
X Consortium Standard, X11R6, April 17, 1994.

\bibitem{x92}
Robert Scheifler, James Gettys, {\em X Window System: The complete Reference
to Xlib, X Protocol, ICCCM, XLFD}, third edition, Digital Press, 1992.

\bibitem{segal92}
Mark Segal, Kurt Akeley, {\em The OpenGL${}^{\rm TM}$ Graphics System:
A Specification}, Version 1.0, Silicon Graphics, June 30, 1992.

\bibitem{sgi91a}
Silicon Graphics, {\em Graphics Library Programming Guide},
Document Number 007-1210-040, 1991.

\bibitem{sgi91b}
Silicon Graphics, {\em Graphics Library Window and Font Library Guide},
Document Number 007-1329-010, 1991.

\end{thebibliography}

\newpage

\addcontentsline{toc}{section}{Index}
\input spec3.ind

\end{document}

